package core.lib.interfaces;

import java.io.DataInputStream;
import java.io.DataOutputStream;
import java.io.IOException;

/*
 * This interface defines the basic capabilities for opening http connections that the SDK core
 * logic must have.
 */
/**
 * 定义了HTTP方式连接的一些操作API。
 */
public interface HttpAgent
{
	/*
	 * Sets the general request property. If a property with the key already exists, overwrite its
	 * value with the new value.<br> <b>Note: </b> HTTP requires all request properties which can
	 * legally have multiple instances with the same key to use a comma-separated list syntax which
	 * enables multiple properties to be appended into a single property.
	 * 
	 * @param key - the keyword by which the request is known (e.g., "accept").
	 * 
	 * @param value - the value associated with it.
	 * 
	 * @throws IOException is thrown if the connection is in the connected state.
	 * 
	 * @see getRequestProperty(java.lang.String)
	 */

	/**
	 * 设置通用请求属性。如果一个属性的键（key）已经存在，则覆盖该值。<br>
	 * 
	 * @param key
	 *            请求已知的的关键字，例如："accept"
	 * @param value
	 *            key关联的值
	 * @throws IOException
	 *             如果连接已经处于连接已连接的状态
	 */
	public void setRequestProperty(String key, String value) throws IOException;

	/*
	 * Open and return an output stream for a connection.
	 * 
	 * @return An output stream
	 * 
	 * @throws IOException If an I/O error occurs
	 */
	/**
	 * 为连接打开并返回一个output stream
	 * 
	 * @return 一个output stream
	 * @throws IOException
	 *             如果I/O发生异常
	 */
	public DataOutputStream openDataOutputStream() throws IOException;

	/*
	 * Open and return an input stream for a connection.
	 * 
	 * @return An input stream
	 * 
	 * @throws IOException If an I/O error occurs
	 */
	/**
	 * 为连接打开并返回一个input stream
	 * 
	 * @return 一个input stream
	 * @throws IOException
	 *             如果I/O发生错误
	 */
	public DataInputStream openDataInputStream() throws IOException;

	/*
	 * Returns the HTTP response status code.It parses responses like: <dd>HTTP/1.0 200 OK</dd> <dd>
	 * HTTP/1.0 401 Unauthorized</dd><br> and extracts the ints 200 and 401 respectively. from the
	 * response (i.e., the response is not valid HTTP).
	 * 
	 * @return the HTTP Status-Code or -1 if no status code can be discerned.
	 * 
	 * @throws IOException
	 */
	/**
	 * 返回HTTP返回状态码。它会被转换成这样的格式：<dd>HTTP/1.0 200 OK</dd><dd>HTTP/1.0 401 Unauthorized</dd><br>
	 * 
	 * @return HTTP Status-Code，如果没有找到状态码则返回-1
	 * @throws IOException
	 */
	public int getResponseCode() throws IOException;

	/*
	 * Returns the length of the content which is being provided. E.g. if the connection is via
	 * HTTP, then the value of the content-length header field is returned.
	 * 
	 * @return the content length of the resource that this connection's URL references, or -1 if
	 * the content length is not known.
	 */
	/**
	 * 返回返回数据的长度。例如：如果连接时通过HTTP的，那么该值将是名为content-length的header的值
	 * 
	 * @return 返回该连接URL所引用地址的资源的长度，如果长度未知则返回-1
	 */
	public long getLength();

	/*
	 * Returns the value of the named header field.
	 * 
	 * @param name - of a header field.
	 * 
	 * @return the value of the named header field, or null if there is no such field in the header.
	 */
	/**
	 * 返回指定名称的header字段值
	 * 
	 * @param name
	 *            一个header字段
	 * @return 以指定名称的header的值，如果没有该header则返回null
	 */
	public String getHeaderField(String name);

	/*
	 * Set the method for the URL request, one of: <ul> <li>GET</li> <li>POST</li> <li>HEAD</li>
	 * </ul> are legal, subject to protocol restrictions. The default method is GET.
	 * 
	 * @param method
	 * 
	 * @throws IOException if the method cannot be reset or if the requested method isn't valid for
	 * HTTP.
	 */
	/**
	 * 设置URL请求方法，一下之一：
	 * <ul>
	 * <li>GET</li>
	 * <li>POST</li>
	 * <li>HEAD</li>
	 * </ul>
	 * 是合法的。默认的方式是GET
	 * 
	 * @param method
	 *            请求方式
	 * @throws IOException
	 *             如果方法不能被重置或者请求的方法在HTTP协议里无效
	 */
	public void setRequestMethod(String method) throws IOException;

	/*
	 * Create and open a http Connection. but the created connection object will not be returned,
	 * the implements should store it
	 * 
	 * @param uri - The URL for the connection.
	 * 
	 * @throws IllegalArgumentException If a parameter is invalid.
	 * 
	 * @throws IOException If some other kind of I/O error occurs.
	 * 
	 * @throws SecurityException May be thrown if access to the protocol handler is prohibited.
	 */
	/**
	 * 创建并打开一个http连接，但是创建后的连接对象不会被返回，接口实现者需要自行保存。
	 * 
	 * @param string
	 *            要连接的URL
	 * @throws IllegalArgumentException
	 *             如果参数不合法，不是URL字符串类型
	 * @throws IOException
	 *             如果发生一些I/O错误
	 */
	public void open(String string) throws IOException, IllegalArgumentException;

	/*
	 * Close the connection created by method {@link #open(String)}
	 * 
	 * @throws IOException If an I/O error occurs
	 */
	/**
	 * 关闭由{@link #open(String)}方法创建的socket连接
	 * 
	 * @throws IOException
	 *             I/O发生错误
	 */
	public void close() throws IOException;

}
